// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_PARSER_FPDF_PARSER_UTILITY_H_
#define CORE_FPDFAPI_PARSER_FPDF_PARSER_UTILITY_H_

#include <iosfwd>
#include <limits>
#include <optional>
#include <vector>

#include "core/fxcrt/bytestring.h"
#include "core/fxcrt/compiler_specific.h"
#include "core/fxcrt/retain_ptr.h"

class CPDF_Array;
class CPDF_Dictionary;
class CPDF_Object;
class IFX_SeekableReadStream;

// Use the accessors below instead of directly accessing kPDFCharTypes.
extern const char kPDFCharTypes[256];

inline uint8_t GetPDFCharTypeFromArray(uint8_t c) {
  static_assert(std::numeric_limits<decltype(c)>::min() == 0);
  static_assert(std::numeric_limits<decltype(c)>::max() <
                std::size(kPDFCharTypes));

  // SAFETY: previous static_asserts show table covers entire range
  // of the index's type.
  return UNSAFE_BUFFERS(kPDFCharTypes[c]);
}

inline bool PDFCharIsWhitespace(uint8_t c) {
  return GetPDFCharTypeFromArray(c) == 'W';
}

inline bool PDFCharIsNumeric(uint8_t c) {
  return GetPDFCharTypeFromArray(c) == 'N';
}

inline bool PDFCharIsDelimiter(uint8_t c) {
  return GetPDFCharTypeFromArray(c) == 'D';
}

inline bool PDFCharIsOther(uint8_t c) {
  return GetPDFCharTypeFromArray(c) == 'R';
}

inline bool PDFCharIsLineEnding(uint8_t c) {
  return c == '\r' || c == '\n';
}

// On success, return a positive offset value to the PDF header. If the header
// cannot be found, or if there is an error reading from |pFile|, then return
// nullopt.
std::optional<FX_FILESIZE> GetHeaderOffset(
    const RetainPtr<IFX_SeekableReadStream>& pFile);

ByteString PDF_NameDecode(ByteStringView orig);
ByteString PDF_NameEncode(const ByteString& orig);

// Return |nCount| elements from |pArray| as a vector of floats. |pArray| must
// have at least |nCount| elements.
std::vector<float> ReadArrayElementsToVector(const CPDF_Array* pArray,
                                             size_t nCount);

// Returns true if |dict| is non-null and has a /Type name entry that matches
// |type|.
bool ValidateDictType(const CPDF_Dictionary* dict, ByteStringView type);

// Returns true if |dict| is non-null and all entries in |dict| are dictionaries
// of |type|.
bool ValidateDictAllResourcesOfType(const CPDF_Dictionary* dict,
                                    ByteStringView type);

// Shorthand for ValidateDictAllResourcesOfType(dict, "Font").
bool ValidateFontResourceDict(const CPDF_Dictionary* dict);

// Like ValidateDictType(), but /Type can also not exist.
bool ValidateDictOptionalType(const CPDF_Dictionary* dict, ByteStringView type);

std::ostream& operator<<(std::ostream& buf, const CPDF_Object* pObj);

#endif  // CORE_FPDFAPI_PARSER_FPDF_PARSER_UTILITY_H_
`fpdf_parser_utility.h` 文件定义了与 PDF 解析相关的实用功能。这些接口提供了有关字符类型判定、PDF 头信息检索、名称编码 / 解码、数组元素读取、字典类型验证等多个方面的支持。以下是接口功能的列表：

### 字符判定函数

1. * *GetPDFCharTypeFromArray(uint8_t c) * *:
-返回字符 `c` 在 `kPDFCharTypes` 数组中对应的字符类型。

2. * *PDFCharIsWhitespace(uint8_t c) * *:
-判断字符 `c` 是否是空白字符。

3. * *PDFCharIsNumeric(uint8_t c) * *:
-判断字符 `c` 是否是数字字符。

4. * *PDFCharIsDelimiter(uint8_t c) * *:
-判断字符 `c` 是否是定界符。

5. * *PDFCharIsOther(uint8_t c) * *:
-判断字符 `c` 是否属于"其他"类别。

6. * *PDFCharIsLineEnding(uint8_t c) * *:
-判断字符 `c` 是否是行尾字符（`\r` 或 `\n`）。

### 其他功能

7. * *GetHeaderOffset(const RetainPtr<IFX_SeekableReadStream>&pFile) * *:
-从 `pFile` 中查找 PDF 头的偏移量。成功时返回正的偏移量，失败时返回 `std::nullopt`。

8. * *PDF_NameDecode(ByteStringView orig) * *:
-对原始的 PDF 名称进行解码。

9. * *PDF_NameEncode(const ByteString & orig) * *:
  -对 PDF 名称进行编码。

  10. * *ReadArrayElementsToVector(const CPDF_Array * pArray, size_t nCount) * *:
  -从 `pArray` 中读取 `nCount` 个元素，返回一个包含这些元素的浮点数向量。

  ### 字典验证功能

  11. * *ValidateDictType(const CPDF_Dictionary * dict, ByteStringView type) * *:
-验证字典 `dict` 是否存在且其 `/Type` 条目的值与 `type` 匹配。

12. * *ValidateDictAllResourcesOfType(const CPDF_Dictionary * dict, ByteStringView type) * *:
-验证字典 `dict` 是否存在且其所有条目都是指定 `type` 的字典。

13. * *ValidateFontResourceDict(const CPDF_Dictionary * dict) * *:
-验证字典 `dict` 是否是有效的字体资源字典（特定形式的字典验证）。

14. * *ValidateDictOptionalType(const CPDF_Dictionary * dict, ByteStringView type) * *:
-类似于 `ValidateDictType()`，但允许 `/Type` 不存在。

### 运算符重载

15. * *std::ostream & operator<<(std::ostream & buf, const CPDF_Object * pObj) * *:
-输出 `CPDF_Object` 对象到输出流 `buf` 中。

这些功能为 PDF 解析中的各种操作提供了便利，适用于字符分析、文档头检索、结构验证等方面。